home *** CD-ROM | disk | FTP | other *** search
/ Delphi Developer's Kit 1996 / Delphi Developer's Kit 1996.iso / power / fbuf / filebuff.doc < prev    next >
Text File  |  1995-12-22  |  6KB  |  142 lines
  1. ═════════════════════════════════════════════════════════════════════════════
  2. Module      : FileBuff.Pas (Version 1.2)
  3. Written     : 05/02/95
  4. Last Update : 05/13/95
  5.  
  6.   Provides simple file buffering for Delphi.  It works only w/ binary
  7.   files and treats that file as a stream of bytes.  Basically it 
  8.   provides the same functionality as BlockWrite() and BlockRead on a 
  9.   Reset(f,1) untyped file.  Also provided is a file BuffTest.Pas which
  10.   is a visual test stub to compare times between unbuffered and the
  11.   current unit.  Since Borland in it's infinite wisdom decided to 
  12.   get rid of TBufStream in this release, here is a suitable 
  13.   replacement.
  14.  
  15.  
  16.        Copyright (c) 1995 Opnek Research. All Rights Reserved.
  17. ═════════════════════════════════════════════════════════════════════════════
  18.  
  19. IMPORTANT!!
  20. -----------
  21. Well, silly me...I uploaded a previous bug version.  Damn that version 
  22. control thing.  Here is the corrected, non-buggy version.  Please replace
  23. any pre-1.2 version of file buffer.  If you don't want the test code, 
  24. get rid of the {$_TESTHARNESS} define.
  25.  
  26.  
  27. Running the Demo
  28. ----------------
  29. I have included a project that encapsulates all this info.
  30. Create a new windows program, and add the TestBuff.pas, Assert.Pas,
  31. TestBuff.dfm and the FileBuff.pas.  Then in your project, define the 
  32. following two conditionals (_NDEBUG, and _TESTHARNESS).  The first 
  33. turns off assert checking and the second includes the test harness 
  34. code in your compilation.  The initial demo writes files of 
  35. 31 x 200000 = 6 meg in length w/ a 32k buffer, so check your disk 
  36. space first.  It creates 4 of these files.  So you must have 24 meg
  37. free before you run, or reduce the records written.  This could take quite
  38. a while to run based on how many records you wish to read/right.
  39.  
  40.  
  41. Files
  42. -----
  43. FileBuff.pas - Contains the actual TBufferedFile object.
  44. Assert.pas   - Module to do asserts, used by FileBuff.pas
  45. TestBuff.pas - Is the test pascal code that calls the testing proc.
  46. TestBuff.??? - Form contents for the test program.
  47.  
  48.  
  49. Distribution Rights
  50. -------------------
  51. I'm not quite sure how to group this software release.  It's purpose
  52. is to promote the exchange of 'handy' modules between programmers to
  53. reduce the tedious task of re-creating the simple stuff.  I'll call it
  54. "EasyWare" for lack of a better term.  You may compile this module in
  55. any application you so chose.  If you find it useful, simply register 
  56. for $10 dollars (US).  You DO NOT have to register to use this library
  57. in your compiled commercial applications.  Registering simply gets you
  58. updates and tells the author thanks.  The only restriction on the use 
  59. of this module is that it may not be incorporated into a large source 
  60. code commercial library.  In otherwords, it's okay to use in your day 
  61. to day and even compiled commercial applications, but you may not 
  62. distribute the code for profit without written consent of the author.  
  63. This prevents a person from gathering up all the "EasyWare" and 
  64. selling a source library for a larger price tag.  Registering the 
  65. software will get you bug fixes and updates to the software.  The 
  66. copyright on the code will still belong to Opnek Research no matter what.
  67.  
  68. I encourage other programmers that have other such libraries to also
  69. distribute your libs via the EasyWare name.  Hopefully after a few 
  70. months, we will have a high-quality low cost set of re-usuable tools.
  71. And all of our lifes will be a little easier.  And hopefully help you
  72. recoup the time you invested in creating the library.
  73.  
  74. I assume no liability whatsoever for your use or misuse of this unit.
  75. Any use of this unit, voids any warranty implied or otherwise.  This 
  76. code, although tested will most likely have at least one bug left in it.
  77.  
  78.  
  79. Usage
  80. -----
  81. Simply read the TestBuff.Pas file, it will explain how the 
  82. TBufferedFile object is compatible w/ the Assign, Reset, Rewrite,
  83. BlockRead/Write procedures.  It's actually pretty simple to implement
  84. and use.
  85.  
  86.  
  87. The Benefits
  88. ------------
  89. If you do alot of copying files, reformatting files or writes of very
  90. small records, the TBufferedFile object will save you a great deal of
  91. time.
  92.  
  93.  
  94.               CreateFile   Copy File   Read File   Modify File In Place
  95.              +-----------+-----------+-----------+----------------------+
  96.   Unbuffered |     56.52 |    122.50 |     44.49 |               118.30 |
  97.              +-----------+-----------+-----------+----------------------+
  98.   Buffered   |     12.80 |     25.59 |      6.37 |                27.19 |
  99.              +-----------+-----------+-----------+----------------------+
  100.  
  101.  
  102. All times are based on 31 byte records w/ a 32,676 buffer size and writing
  103. out 200,000 records.  The times are in seconds.
  104.  
  105. Just to give you a frame of reference.  If I read a file of the above size 
  106. at 64k bytes a shot, no other processing, it will take the system 4.51 
  107. seconds to read the file.  To write the file 64k at a time it takes 7.91 
  108. seconds.  That is with no processing other than looping and blockwriting 
  109. 64k at a time.  BTW, the test program allows you to change the parameters 
  110. and see how much your application will benefit from file buffering.  The 
  111. larger your record size, the less file buffering will help.
  112.  
  113.  
  114. Contacting the Author
  115. ---------------------
  116. You can email me with bugs, problems, comments, questions, etc... at
  117. Compuserve [74002,2212] Jay Cole.  If you would like to see some 
  118. enhancements, please feel free to drop me a line, I'll see if I can add
  119. it.  
  120.  
  121. Registering the Software
  122. ------------------------
  123. Send $10US, Check or Money Order to :
  124.  
  125.   Jay Cole
  126.   809 Mooreland Drive
  127.   Bowling Green, KY 42103
  128.  
  129.   Again, it is NOT required to register for you to use this product in your
  130.   systems.  Drop me an E-Mail if you find it useful.
  131.  
  132.  
  133. Final Notes
  134. -----------
  135. The module Asserts is included to provide Assert() capability that I have
  136. grown to like w/ C, C++.  Unfortunately, no macro facility is available
  137. in Delphi, so I use the kludgy conditional compiles.  Seems to work pretty
  138. well.  If you wan't to know more about Asserts() read "Writing Solid Code"
  139. by Steven Maquire.  Microsoft Press.  An excellent book on bullet proofing
  140. your code.  BTW, Asserts() is a totally free EasyWare module.  No 
  141. registration required.
  142.